<HTML><HEAD><TITLE>library(mode_analyser)</TITLE></HEAD><BODY>
[ <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]<H1>library(mode_analyser)</H1>
Instrumentation based mode analyser
<H2>Predicates</H2>
<BLOCKQUOTE>
<DL>
<DT><A HREF="analyse-1.html"><STRONG>analyse(+File)</STRONG></A></DT>
<DD>Compile a file, inserting invocation mode analysis 
   instrumentation for each predicate definition.</DD>
<DT><A HREF="reset-0.html"><STRONG>reset</STRONG></A></DT>
<DD>Reset the mode analysis results for predicates compiled 
   into the calling context module.</DD>
<DT><A HREF="result-0.html"><STRONG>result</STRONG></A></DT>
<DD>Produce the mode analysis results for predicates 
   compiled into the calling context module.</DD>
<DT><A HREF="result-1.html"><STRONG>result(+OptionList)</STRONG></A></DT>
<DD>Produce the mode analysis results for predicates
   compiled into the calling context module.</DD>
</DL>
</BLOCKQUOTE>
<H2>Description</H2>
<P>
    The mode_analyser library is a tool that assists in the determination of
    the mode/1 directive for predicate definitions. This directive informs
    the compiler that the arguments of the specified predicate will always 
    have the corresponding form when the predicate is called. The compiler 
    utilises this information during compilation of the predicate in order
    to generate more compact and/or faster code. Specifying the mode of a 
    predicate that has already been compiled has no effect, unless it is 
    recompiled. If the specified procedure does not exist, a local
    undefined procedure is created.
</P><P>
    The mode analyser inserts instrumentation into the clause definitions of
    predicates during compilation in order to record mode usage of each 
    predicate argument. The code should then be run (as many times as is
    necessary to capture the most common invocations of each predicate 
    undergoing analysis). Finally, the results of the analysis are requested
    and the suggested mode annotations for each predicate are displayed.
</P><P>
    NOTE: It is imperative to understand that the results of mode analysis 
    are merely suggestions for the invocation modes of a predicate based on 
    runtime information. If there are potential predicate invocation modes 
    that were not exercised during runtime, the tool is unable to account 
    for them in its analysis. For the mode specifier '-' the mode analyser
    does not determine whether the variable occurs in any other argument
    (i.e. is aliased), this must be manually verified. 
    In summary, the programmer must verify that the suggested modes are correct 
    before using the directive in the code.  If the instantiation of the 
    predicate call violates its mode declaration, no exception is raised and 
    its behaviour is undefined.
</P><P>
	The usage is as follows:
	<OL>
	<LI>Load the mode_analyser library
	<PRE>
	?- lib(mode_analyser).
	</PRE>
	<LI>Compile your program with the mode analyser compiler
    <PRE>
	?- mode_analyser:analyse(my_program).
	</PRE>
	<LI>Run the query for which you wish to generate mode analysis data
	<PRE>
	?- my_query(X,Y,Z).
	</PRE>
	<LI>Generate the results for the module into which the program
        was compiled.
	<PRE>
	?- mode_analyser:result(my_program_module).
	</PRE>
</P><P>
	Limitations to be resolved shortly: 
	<OL>
    <LI>A future enhancement will enable the insertion of the suggested 
    (or programmer ammended) mode/1 directives for each predicate
    definition into the source code.
    </OL>
</P>
<H2>About</H2><UL COMPACT>
<LI><STRONG>Status: </STRONG>prototype
<LI><STRONG>Author: </STRONG>Andrew Cheadle
<LI><STRONG>Copyright &copy; </STRONG>Cisco Systems, Inc.
<LI><STRONG>Date: </STRONG>$Date: 2009/02/19 06:09:22 $
</UL>
<HR>Generated from mode_analyser.eci on 2009-05-27 01:25
</BODY></HTML>
